<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
            "http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>



<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<META name="GENERATOR" content="hevea 1.08">
<LINK rel="stylesheet" type="text/css" href="embroot.css">
<TITLE>
Incompatible and obsolete commands
</TITLE>
</HEAD>
<BODY >
<A HREF="embroot024.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="embroot016.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<HR>

<H2 CLASS="section"><A NAME="htoc46">5.9</A>&nbsp;&nbsp;Incompatible and obsolete commands</H2>
Here is a list of commands in the embedding interface that are retained for
compatibility purposes with previous versions. They have no equivalent in
the Tcl remote interface, and their use for new code is discouraged.
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
<A NAME="@default110"></A><B>ec_post_goal <I>goal ?format?</I></B><DD CLASS="dd-description"><BR>
post a goal that will be executed when ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> is resumed.
	If no <I>format</I> argument is given, the goal is taken to be a string
	in ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> syntax. Note that (unlike with the C/C++
	interface) it is not possible to retrieve any variable
	bindings from ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> after successful execution of the
	goal.
	To pass information from ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> to Tcl, use queue streams
	as described later on. Example:
	<PRE CLASS="verbatim">
 ec_post_goal {go("hello",27)}
 </PRE>
	If a <I>format</I> argument is provided, the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> goal is
	constructed from <I>goal</I> data and <I>format</I>, according to
	the conversion rules explained in section <A HREF="embroot024.html#secexdrtcl">5.8</A>. Example:
	<PRE CLASS="verbatim">
 ec_post_goal {go hello 27} (SI)
 </PRE>
	Posting several goals is the same as posting the conjunction
	of these goals. Note that simple, deterministic goals can be
	executed independently of the posted goals using the <B>	ec_rpc</B> command (see below).<BR>
<BR>
<DT CLASS="dt-description"><A NAME="@default111"></A><B>ec_post_event <I>event_name</I></B><DD CLASS="dd-description"><BR>
Post an event to the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> engine. This will lead to the
 execution of the corresponding event handler once the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>
 execution is resumed. See also <A HREF="../bips/kernel/event/event-1.html"><B>event/1</B></A><A NAME="@default112"></A> and the User Manual
 chapter on event handling for more information.
 This mechanism is mainly recommended for asynchronous posting
 of events, e.g. from within signal handlers or to abort execution.
 Otherwise it is more convenient to raise an event by writing into
 an event-raising queue stream (see section <A HREF="embroot022.html#secqevent">5.6.2</A>).<BR>
<BR>
<DT CLASS="dt-description"><A NAME="@default113"></A><B>ec_handle_events</B><DD CLASS="dd-description"><BR>
resume execution of the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> engine for the purpose of
	event handling only. All events that have been posted via
	ec_post_event or raised by writing into event-raising queues
	will be handled (in an unspecified order).
	The return value will always be "success", except when an
	asynchronous ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> thread is still running, in which case
	the return value is "running" and it is undefined whether the
	events may have been handled by that thread or not.<BR>
<BR>
first create an ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> queue stream using ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>'s
<A HREF="../bips/kernel/iostream/open-3.html"><B>open/3</B></A><A NAME="@default114"></A>
or
<A HREF="../bips/kernel/iostream/open-4.html"><B>open/4</B></A><A NAME="@default115"></A>
predicate, then connect that stream to a Tcl channel by invoking
the <B>ec_queue_connect</B> command from within Tcl code.<BR>
<BR>
<DT CLASS="dt-description"><A NAME="@default116"></A><B>ec_queue_connect <I>eclipse_stream_name mode ?command?</I></B><DD CLASS="dd-description"><BR>
Creates a Tcl channel and connects it to the given ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>
 stream (<I>eclipse_stream_name</I> can be a symbolic name or the
 ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> stream number).
 The <I>mode</I> argument is either r or w, indicating a read or write channel.
 The procedure returns a channel identifier for use in commands
 like <B>puts</B>, <B>read</B>, <B>ec_read_exdr</B>,
 <B>ec_write_exdr</B> or <B>close</B>.
 The channel identifier is of the form <TT>ec_queueX</TT>, where <TT>X</TT>
 is the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> stream number of the queue.
 This identifier can either be stored in a variable or reconstructed
 using the Tcl expression
 <PRE CLASS="verbatim">
        ec_queue[ec_stream_nr eclipse_stream_name]
        </PRE>	If a <I>command</I> argument is provided, this command is set as the
	handler to be called when data needs to be flushed or read from
	the channel (see <B>ec_set_queue_handler</B>).<BR>
<BR>
<DT CLASS="dt-description"><A NAME="@default117"></A><B>ec_set_queue_handler <I>eclipse_stream_name mode command</I></B><DD CLASS="dd-description"><BR>
	Sets <I>command</I> as the Tcl-handler to be called when the
	specified queue needs to be serviced from the Tcl side.
	Unlike <B>ec_queue_connect</B>, this command does not create
	a Tcl channel.
	The <I>mode</I> argument is either r or w, indicating whether
	the Tcl end of the queue is readable or writable.
	For readable queues, the handler is invoked when the
	ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side flushes the queue. The Tcl-handler is
	expected to read and empty the queue.
	For writable queues, the handler is invoked when the
	ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side reads from the empty queue. The Tcl-handler is
	expected to write data into the queue.
	In any case, the handler <I>command</I> will be invoked with
	the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> stream number appended as an extra argument.</DL>
<HR>
<A HREF="embroot024.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="embroot016.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
</BODY>
</HTML>
